home *** CD-ROM | disk | FTP | other *** search
/ SGI Origin & Onyx2 Patches 1998 May / Origin and Onyx2 System Disk Patches May 1998.img / dist / patchSG0002048.idb / usr / include / vme_dma_engine.h.z / vme_dma_engine.h
C/C++ Source or Header  |  1997-12-08  |  7KB  |  238 lines
  1. /*
  2.  * Copyright 1996, Silicon Graphics, Inc.
  3.  * ALL RIGHTS RESERVED
  4.  *
  5.  * UNPUBLISHED -- Rights reserved under the copyright laws of the United
  6.  * States.   Use of a copyright notice is precautionary only and does not
  7.  * imply publication or disclosure. 
  8.  *
  9.  * U.S. GOVERNMENT RESTRICTED RIGHTS LEGEND:
  10.  * Use, duplication or disclosure by the Government is subject to restrictions
  11.  * as set forth in FAR 52.227.19(c)(2) or subparagraph (c)(1)(ii) of the Rights
  12.  * in Technical Data and Computer Software clause at DFARS 252.227-7013 and/or
  13.  * in similar or successor clauses in the FAR, or the DOD or NASA FAR
  14.  * Supplement.  Contractor/manufacturer is Silicon Graphics, Inc.,
  15.  * 2011 N. Shoreline Blvd. Mountain View, CA 94039-7311.
  16.  *
  17.  * THE CONTENT OF THIS WORK CONTAINS CONFIDENTIAL AND PROPRIETARY
  18.  * INFORMATION OF SILICON GRAPHICS, INC. ANY DUPLICATION, MODIFICATION,
  19.  * DISTRIBUTION, OR DISCLOSURE IN ANY FORM, IN WHOLE, OR IN PART, IS STRICTLY
  20.  * PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF SILICON
  21.  * GRAPHICS, INC.
  22.  */
  23.  
  24. #ident "$Revision: 1.3 $"
  25.  
  26. /* User interface for VME DMA engine */
  27.  
  28. #ifndef __VME_DMA_ENGINE_H__
  29. #define __VME_DMA_ENGINE_H__
  30.  
  31. #include <sys/types.h>
  32. #include <sys/vme/vmeio.h>
  33.  
  34. /* Opaque handle representing the DMA engine */
  35. typedef struct vme_dma_engine_handle_s * vme_dma_engine_handle_t;
  36.  
  37. /* Opaque handle representing the DMA buffer */
  38. typedef struct vme_dma_engine_buffer_s * vme_dma_engine_buffer_t;
  39.  
  40. /* Opaque handle representing the transfer object */
  41. typedef struct vme_dma_engine_transfer_s * vme_dma_engine_transfer_t;
  42.  
  43. /* ----------------------------------------------------------------------
  44.  * 
  45.  * Acquire the DMA engine 
  46.  *
  47.  * ---------------------------------------------------------------------- */
  48.  
  49. /* Flag passed in vme_dma_engine_handle_alloc() */
  50. #define VME_DMA_ENGINE_DEBUG       (0x0001)  
  51.  
  52. /* Return: handle of the DMA engine if success; 0 if failure */
  53. extern vme_dma_engine_handle_t 
  54. vme_dma_engine_handle_alloc(char *,         /* Hardware graph pathname */
  55.                 unsigned int);  /* Flags                   */
  56.  
  57. /* ----------------------------------------------------------------------
  58.  * 
  59.  * Prepare DMA buffer
  60.  *
  61.  * ---------------------------------------------------------------------- */
  62.  
  63. /*
  64.  * If the user gives a virtual address 0, we will create a 
  65.  * virtual address range for the user.
  66.  * Return: handle of the buffer if success; 0 if failure.
  67.  */
  68. extern vme_dma_engine_buffer_t
  69. vme_dma_engine_buffer_alloc(vme_dma_engine_handle_t,
  70.                 void *,  /* User process virtual address */
  71.                 size_t); /* Length of the buffer */
  72.  
  73.  
  74. /* 
  75.  * Get the user virtual address out of the buffer handle
  76.  */
  77. extern void *
  78. vme_dma_engine_buffer_vaddr_get(vme_dma_engine_buffer_t);
  79.  
  80. /* ----------------------------------------------------------------------
  81.  * 
  82.  * Allocate a transfer handle
  83.  *
  84.  * ---------------------------------------------------------------------- */
  85.  
  86.  
  87. /* Users have to specify which way the DMA is going */
  88. typedef enum {
  89.     VME_DMA_ENGINE_DIR_READ,
  90.     VME_DMA_ENGINE_DIR_WRITE
  91. } vme_dma_engine_dir_t;
  92.  
  93. /* 
  94.  * User can choose their preferred throttle value. However, the system
  95.  * can decide what's used for the transfer given the software and
  96.  * hardware constraint.  
  97.  */
  98. typedef enum {
  99.     VME_DMA_ENGINE_THROTTLE_256,
  100.     VME_DMA_ENGINE_THROTTLE_512,
  101.     VME_DMA_ENGINE_THROTTLE_1024,
  102.     VME_DMA_ENGINE_THROTTLE_2048,
  103.     VME_DMA_ENGINE_THROTTLE_4096,
  104.     VME_DMA_ENGINE_THROTTLE_8192,
  105.     VME_DMA_ENGINE_THROTTLE_16384,
  106.     VME_DMA_ENGINE_THROTTLE_DEFAULT
  107. } vme_dma_engine_throttle_t;
  108.  
  109. /* 
  110.  * User can choose to release the bus when done, or release the bus on
  111.  * request. However, the system can decide what's used for the transfer given 
  112.  * the software and hardware constraint.  
  113.  */
  114. typedef enum {
  115.     VME_DMA_ENGINE_RELEASE_DONE,
  116.     VME_DMA_ENGINE_RELEASE_DEMAND,
  117.     VME_DMA_ENGINE_RELEASE_DEFAULT
  118. } vme_dma_engine_release_t;
  119.    
  120. /* 
  121.  * Note: it is user's responsibility to prepare the VME device.
  122.  * Return: 0 if success, -1 if failure
  123.  */
  124. extern vme_dma_engine_transfer_t
  125. vme_dma_engine_transfer_alloc(vme_dma_engine_handle_t,    /* Engine handle   */
  126.                   vme_dma_engine_buffer_t,    /* DMA buffer      */
  127.                   iopaddr_t,                  /* device address  */
  128.                   size_t,                     /* Transfer size   */
  129.                   vme_dma_engine_dir_t,       /* Xfer direction  */
  130.                   vmeio_am_t,                 /* Addr modifier   */
  131.                   vme_dma_engine_throttle_t,  /* Throttle size   */
  132.                   vme_dma_engine_release_t);  /* Release mode    */
  133.  
  134.  
  135. /* ----------------------------------------------------------------------
  136.  * 
  137.  * Schedule a transfer for future DMA 
  138.  * 
  139.  * ---------------------------------------------------------------------- */
  140.  
  141.  
  142. /* 
  143.  * User can schedule multiple transfers for one continuous DMA operation.
  144.  * Return: 0 if success, -1 if failure.
  145.  */
  146. extern int 
  147. vme_dma_engine_schedule(vme_dma_engine_handle_t,
  148.             vme_dma_engine_transfer_t);
  149.  
  150. /* ----------------------------------------------------------------------
  151.  * 
  152.  * Present our schedule of transfers to the DMA enigne.
  153.  * 
  154.  * ---------------------------------------------------------------------- */
  155.  
  156. /* 
  157.  * Users can choose to block here until the DMA is finished, or 
  158.  * do something else in the meanwhile and come back later for the data.
  159.  * if the user chooses to block here, he/she could also choose to wait by 
  160.  * spinning or sleeping.
  161.  */
  162. typedef enum {
  163.     VME_DMA_ENGINE_COMMIT_BLOCK,
  164.     VME_DMA_ENGINE_COMMIT_NONBLOCK
  165. } vme_dma_engine_commit_t;
  166.  
  167. /* 
  168.  * In the Sync mode, users can choose to spin wait on the engine to service 
  169.  * its request, or sleep wait on the engine to finish the service.
  170.  * This is an advisory value.
  171.  */
  172. typedef enum {
  173.     VME_DMA_ENGINE_WAIT_SPIN,
  174.     VME_DMA_ENGINE_WAIT_SLEEP,
  175.     VME_DMA_ENGINE_WAIT_DEFAULT
  176. } vme_dma_engine_wait_t;
  177.  
  178. /* 
  179.  * Return: 0 if success, -1 if failure
  180.  */
  181. extern int 
  182. vme_dma_engine_commit(vme_dma_engine_handle_t,
  183.               vme_dma_engine_commit_t,
  184.               vme_dma_engine_wait_t);
  185.  
  186. /* 
  187.  * Check to see if the DMA is finished.
  188.  * Return: 1 if DMA transfer finishes, 0 if not
  189.  */
  190. extern int
  191. vme_dma_engine_isdone(vme_dma_engine_handle_t);
  192.  
  193. /* 
  194.  * If the asychronous mode is selected, wait on the DMA engine to finish 
  195.  * the DMA for scheduled transfers.  
  196.  * Return: 0 if success, -1 if failure
  197.  */
  198. extern int 
  199. vme_dma_engine_rendezvous(vme_dma_engine_handle_t, 
  200.               vme_dma_engine_wait_t);
  201.  
  202. /* ----------------------------------------------------------------------
  203.  * 
  204.  * Resource deallocation
  205.  * 
  206.  * ---------------------------------------------------------------------- */
  207.  
  208. /*
  209.  * Free the transfer handle 
  210.  */
  211. extern void
  212. vme_dma_engine_transfer_free(vme_dma_engine_handle_t,
  213.                  vme_dma_engine_transfer_t);
  214.  
  215.  
  216. /* 
  217.  * Tear down the buffer for DMA
  218.  * Note: Since one buffer ties up the DMA resources in the system, it's 
  219.  *       sometimes good to free up the DMA resources if we decide to free up 
  220.  *       the resources and let other DMA get the resources
  221.  */
  222. extern void 
  223. vme_dma_engine_buffer_free(vme_dma_engine_handle_t,
  224.                vme_dma_engine_buffer_t);
  225.  
  226. /*
  227.  * Release the DMA engine
  228.  */
  229. extern void 
  230. vme_dma_engine_handle_free(vme_dma_engine_handle_t);
  231.  
  232. #endif /* __VME_DMA_ENGINE_H__ */
  233.  
  234.  
  235.  
  236.  
  237.  
  238.